%
% `SGEphemeris.tex' -- describes the SGEphemeris class
%
%  Docs written by Curtis Olson.  Started July, 2000.
%
% $Id: SGEphemeris.tex,v 1.1.1.1 2002/09/07 02:58:20 curt Exp $
%------------------------------------------------------------------------


\documentclass[12pt]{article}

\usepackage{anysize}
\papersize{11in}{8.5in}
\marginsize{1in}{1in}{1in}{1in}

\usepackage{amsmath}

\usepackage{epsfig}

\usepackage{setspace}
\onehalfspacing

\usepackage{url}


\begin{document}


\title{
    SimGear \texttt{SGEphemeris} class.
}


\author{
    Durk Talsma (\texttt{d.talsma@direct.a2000.nl}) \\
    Curtis Olson (\texttt{curt@flightgear.org})
}


\maketitle


\section{Introduction}

The \texttt{SGEphemeris} class computes and stores the positions of
the Sun, the Moon, the planets, and the brightest stars.  These
positions can then be used to accurately render the dominant visible
items in the Earth's sky.  Note, this class isn't intended for use in
an interplanetary/interstellar/intergalactic type application.  It is
calculates everything relative to the Earth and is therefore best
suited for Earth centric applications.


\section{Synopsis}

\begin{verbatim}
#include <simgear/ephemeris/ephemeris.hxx>

SGEphemeris ephem( const string& path );
\end{verbatim}


\section{\texttt{SGEphemeris}}

The positions of the various astronomical objects are time dependent,
so to maintain accuracy, you will need to periodically call the
\texttt{update()} method.  The \texttt{SGTime} class conveniently
provides the two time related values you need to pass to the
\texttt{update()} method.

\subsection{Constructor}

\begin{verbatim}
SGEphemeris ephem( const string& path );
\end{verbatim}

This creates an instance of the \texttt{SGEphemeris} object.  When
calling the constructor you need to provide a path pointing to your
star database file.

\subsection{Periodic Updates}

\begin{verbatim}
// Update (recalculate) the positions of all objects for the
// specified time
void update(double mjd, double lst, double lat);
\end{verbatim}

The \texttt{update()} method requires you to pass in the current
modified Julian date, the current local sidereal time, and the current
latitude.  The \texttt{update()} method is designed to be called by
the host application before every frame.


\section{Accessor Methods}

Once an instance of \texttt{SGEphemeris} has been successfully initialized,
you may access valid data from it.

\begin{verbatim}
Star *get_sun()
\end{verbatim}

Returns a pointer to a Star class containing all the positional
information for Earth's Sun.

\begin{verbatim}
double getSunRightAscension()
\end{verbatim}

Returns the right ascension of the Sun.

\begin{verbatim}
double getSunDeclination()
\end{verbatim}

Returns the declination of the Sun.

\begin{verbatim}
Moon *get_moon()
\end{verbatim}

Returns a pointer to a Moon class containing all the positional
information for Earth's Moon.

\begin{verbatim}
double getMoonRightAscension()
\end{verbatim}

Returns the right ascension of the Moon.

\begin{verbatim}
double getMoonDeclination()
\end{verbatim}

Returns the declination of the Moon.

\begin{verbatim}
int getNumPlanets()
\end{verbatim}

Returns the numbers of defined planets.

\begin{verbatim}
sgdVec3 *getPlanets()
\end{verbatim}

Returns a pointer to an array of planet data in sgdVec3 format.  (See
plib.sourceforge.net for information on plib and the ``sg'' package.)
An sgdVec3 is a 3 element double array.  The first element is the
right ascension of the planet, the second is the declination, and the
third is the magnitude.

\begin{verbatim}
int getNumStars()
\end{verbatim}

Returns the numbers of defined stars.

\begin{verbatim}
sgdVec3 *getPlanets()
\end{verbatim}

Returns a pointer to an array of star data in sgdVec3 format.  An The
first element of the sgdVec3 is the right ascension of the planet, the
second is the declination, and the third is the magnitude.


\end{document}
